home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 4 / MacMania 4.toast / / Demo's / Igor Demo Pro / 1 PutContentsIn Igor Pro Folder / More Extensions / File Loaders / TDLoadWave Documentation < prev   
Text File  |  1994-03-24  |  10KB  |  232 lines
  1. *** TDLoadWave XOP, Version 1.20, 3/24/94 ***
  2.  
  3. TDLoadWave adds a 'Load Tab-delimited File' item to the 'Load Waves'
  4. submenu of Igor's 'File' menu. It also adds the TDLoadWave and TDSaveWave
  5. operations to Igor.
  6.  
  7. Igor Pro users should use the delimited-text file loading and saving
  8. capability that is built-in to Igor Pro. Use TDLoadWave only if you
  9. want to run under Igor 1.2.
  10.  
  11. TDLoadWave behaves much like the built-in LoadWave operation
  12. in Igor 1.2 except for the following:
  13.         it loads tab-delimited files with missing values
  14.         it will look for column names in the file it is loading
  15.         the number of rows and columns that it can load is unlimited
  16.         it can be made to skip columns under macro control
  17.  
  18. The TDLoadWave XOP also adds an TDSaveWave operation which you can
  19. access through the command line but has no menu item.
  20.  
  21. To use this or any other XOP you must put the XOP file in the folder
  22. containing the Igor 1.2 application and then launch Igor 1.2.
  23.  
  24. There are some release notes about this version of TDLoadWave at the
  25. end of this file.
  26.  
  27. TDLoadWave is designed to load data from "tab-delimited files".
  28. This means that the text in the file is of the form:
  29.     number    tab    number    tab   number   carriage-return
  30.  
  31. This is a very common Macintosh file format. If your file does not
  32. have this format, TDLoadWave will not be able to load it.
  33.  
  34. TDLoadWave starts out by trying to determine the number of columns
  35. in the file. It does this by counting tabs in the first row of text.
  36.  
  37. TDLoadWave then looks at the first row in the file and determines if
  38. the file contains column names. It does this by looking at the first
  39. non-white-space character. If this is an alpha character,
  40. TDLoadWave assumes that the row contains column names. If it is a
  41. numeric character TDLoadWave decides that the file does not contain
  42. column names.
  43.  
  44. If your file contains column names but they are not in the first row,
  45. or contains other garbage at the beginning that you want to skip,
  46. you can force TDLoadWave to skip some rows by using the /S option,
  47. described below.
  48.  
  49. TDLoadWave creates and sets the file-loader output variables
  50. V_flag, S_fileName and S_waveNames. It sets V_flag to the
  51. number of waves loaded. It sets S_fileName to the name of the
  52. file loaded for use in annotating a graph. It sets S_waveNames
  53. to a semicolon-separated list of the names of the waves that were
  54. loaded.
  55.  
  56. You can access TDLoadWave through its menu item or by invoking the 
  57. TDLoadWave operation from the command line or from a macro.
  58.  
  59. *** TDLoadWave Operation ***
  60.  
  61. The TDLoadWave operation has the following syntax:
  62.  
  63. TDLoadWave [[/P=path]/O/D/I/T/Q/A[=basename]] "filename"
  64.  
  65.     /P=path specifies a path where file can be found.
  66.     /O causes new waves to overwrite existing waves of the same name.
  67.     /D causes the new waves to be double precision.
  68.     /I causes TDLoadWave to put up the standard open dialog.
  69.     /Q suppresses normal diagnostic messages during load.
  70.     /N like /A but reuses existing names.
  71.     /N=basename like /A but reuses existing names.
  72.     /T inhibits trimming of missing data points from the end of waves
  73.     /S={skipBefore, skipAfter, maxRows, startCol, endCol, colControlString}
  74.  
  75. If neither /A nor /N is used then wave names are generated from
  76. the column names in the file. If there are no column names in the file, the
  77. default "Column" is used as a base name.
  78.  
  79.     "filename" is a full file name for the file to load
  80.     or a partial file name if /P is used.
  81.     If "filename" is omitted TDLoadWave puts up the standard open dialog.
  82.  
  83. The /S={...} option allows you to force TDLoadWave to skip some of the
  84. rows and/or columns in the file:
  85.     skipBefore is the number of lines of text to skip before attempting to
  86.     determine the number of columns in the file or to read column names
  87.         from the file.
  88.  
  89.     skipAfter is the number of lines of text to skip after reading column
  90.       names from the file. If TDLoadWave finds no column names then it
  91.     ignores this parameter.
  92.  
  93.         maxRows is the maximum number of rows of numeric data that
  94.         TDLoadWave will load. This parameter lets you read a subset of the rows
  95.         in the file. If it is zero then this means "load all the rows in the file".
  96.  
  97.     startCol, endCol and colControlString work together to allow you to
  98.     load a subset of the columns in the file.
  99.  
  100.         If colControlString is "" then startCol and endCol set the first and last
  101.         column to load. 0 is the first column in the file. If endCol is 0 then
  102.     endCol is taken to be the last column in the file.
  103.  
  104.         If colControlString is something other than "" then it controls what
  105.     columns are loaded. In this case TDLoadWave ignores startCol and endCol.
  106.  
  107.         Each character in colControlString controls the loading of one column.
  108.     If the character is '0' (the digit zero), then the column is NOT loaded.
  109.     If the character is anything other than '0', the column IS loaded.
  110.       If there are more columns in the file than characters in colControlString,
  111.     then TDLoadWave fills colControlString out with '0' characters.
  112.  
  113.         colControlString can not exceed 256 characters.
  114.  
  115.         Here are some examples using /S={...}. These examples assume that you
  116.         have created a symbolic path with the name thePath and that the folder
  117.         identified by thePath contains a tab-delimited file with the name "Data".
  118.  
  119.           | Load all rows and columns (same as if /S={...} were omitted
  120.           TDLoadWave/P=thePath/S={0, 0, 0, 0, 0, ""} "Data"
  121.  
  122.           | Skip 5 lines, look for name row, then load up to 100 rows
  123.           TDLoadWave/P=thePath/S={5, 0, 100, 0, 0, ""} "Data"
  124.  
  125.           | Look for name row, skip 100 rows, then load till end of file
  126.           TDLoadWave/P=thePath/S={0, 100, 0, 0, 0, ""} "Data"
  127.  
  128.           | Load columns 1 through 3 (1 is the second column in the file)
  129.           TDLoadWave/P=thePath/S={0, 0, 0, 1, 3, ""} "Data"
  130.  
  131.           | Load columns 0, 3, 4 and 6
  132.           TDLoadWave/P=thePath/S={0, 0, 0, 0, 0, "1001101"} "Data"
  133.  
  134.           | Load up to 75 rows starting from row 50 but only in columns 27-35
  135.           TDLoadWave/P=thePath/S={50, 0, 75, 27, 35, ""} "Data"
  136.  
  137.  
  138. *** TDSaveWave Operation ***
  139.  
  140. You can access the TDSaveWave operation from the command line or from a
  141. macro. It has the following syntax:
  142.  
  143. TDSaveWave [[/P=path]/O/I/Q] wavelist [as "filename"]
  144.  
  145.     /P=path specifies a path in which to save file.
  146.     /O causes an existing file of the same name to be overwritten
  147.     /I causes TDSaveWave to put up the standard save dialog.
  148.     /Q suppresses normal diagnostic messages during save.
  149.  
  150.       wavelist is a list of wave names to save.
  151.  
  152.     There are two ways to specify the wave list.
  153.     Normally you would use a comma-separated list of wave names:
  154.         TDSaveWave/P=path wave0, wave1, wave2 as "fileName"
  155.     This technique is limited by the fact that the Igor command line can hold no
  156.     more than 200 characters.
  157.  
  158.     The second way uses an Igor string variable to contain a comma or
  159.     semicolon-separated list of wave names:
  160.         String waves
  161.         waves = "wave0, wave1, wave2"
  162.         waves += ", wave3, wave4, wave5"
  163.         TDSaveWave/P=path $waves as "fileName"
  164.     Using this technique the number of waves that you can write to a file is
  165.     limited only by available memory.
  166.  
  167.     "filename" is a full file name for the file to save
  168.     or a partial file name if /P is used.
  169.     If as "filename" is omitted TDSaveWave puts up the standard save dialog.
  170.  
  171.     Double precision waves are saved with up to 15 digits of precision.  Complex
  172.     waves are saved as two columns.  The column names have .real and .imag suffexes.
  173.  
  174.  
  175. ***** RELEASE NOTES **********
  176.  
  177. *** Release 1/17/92 ***
  178.  
  179. This version of TDLoadWave is much faster than the original. On a MacIIfx
  180. the new version is more than 6 times faster than the original version when
  181. loading local large files and is more than 20 times faster when loading files
  182. from a file server.
  183.  
  184. Note: with heroic effort TDLoadWave could be made even faster - perhaps
  185. more than twice as fast.  If this would be important to you please let us
  186. know.
  187.  
  188. TDLoadWave can take a new flag, /T, that inhibits the automatic trimming
  189. of missing data points from the end of waves.
  190.  
  191. Columns containing only a single data point after trimming are no longer
  192. discarded.
  193.  
  194. TDLoadWave attempts to be less easily confused by files that don't
  195. have a consistent number of tabs in each row.  The number of columns in
  196. the file is taken from the number of tabs in the first  row.  If later rows
  197. have too many columns then the excess data is discarded. If later rows have
  198. too few columns then missing data values (NaNs) are used for the remaining
  199. columns.
  200.  
  201. The new TDSaveWave allows up to 50 waves to be saved where the old
  202. only allowed 8.  (Actually we don't think TDSaveWave ever worked)  In order
  203. to save 40 waves the names had better be very short since the list has to
  204. fit on one line.
  205.  
  206. *** Release 5/5/92 ***
  207.  
  208. In this version we added the /S={...} option. This allows you to make
  209. TDLoadWave skip various rows and/or columns so that you can load
  210. a subset of a file.
  211.  
  212. Changed things so that if TDLoadWave finds a column name that conflicts
  213. with an Igor function or operation (e.g. "Time"), it will change the name
  214. by prepending "X_" (e.g. "X_Time"). Previously, it would have just given
  215. an error message and quit.
  216.  
  217. *** Release 8/3/92 ***
  218.  
  219. In this release we added the $<string variable> syntax to TDSaveWave.
  220. This allows you to save any number of waves.
  221.  
  222. *** Release 3/24/94, version 1.20 ***
  223.  
  224. This version adds support for the file-loader output variable
  225. S_waveNames which TDLoadWave sets to a semicolon-separated
  226. list of the names of the waves that were loaded.
  227.  
  228. Previous versions set the file-loader output variable S_fileName
  229. only if it existed. This version will create it if it does not exist.
  230.  
  231.  
  232.